home *** CD-ROM | disk | FTP | other *** search
/ Mac Format 1995 June / MacFormat 25.iso / Shareware City / Developers / ICProgKit1.0 / APIs / ICAPI.h next >
Text File  |  1994-11-27  |  5KB  |  119 lines
  1. /*
  2.     The canonical Internet Config interface is defined in Pascal.  These headers have
  3.     not been thoroughly tested.  If there is a conflict between these headers and the
  4.     Pascal interfaces, the Pascal should take precedence.
  5. */
  6.  
  7. /* ///////////////////////////////////////////////////////////////////////////////// */
  8.  
  9. #ifndef __ICAPI__
  10. #define __ICAPI__
  11.  
  12. #ifndef __TYPES__
  13. #include <Types.h>
  14. #endif
  15.  
  16. #ifndef __FILES__
  17. #include <Files.h>
  18. #endif
  19.  
  20. #ifndef __ICTYPES__
  21. #include <ICTypes.h>
  22. #endif
  23.  
  24. /* ///////////////////////////////////////////////////////////////////////////////// */
  25.  
  26. #ifdef __cplusplus
  27. extern "C" {
  28. #endif
  29.  
  30.     pascal ICError ICStart(ICInstance *inst, OSType creator);
  31.     /* call at application initialisation */
  32.  
  33.     pascal ICError ICStop(ICInstance inst);
  34.     /* call at application termination */
  35.  
  36.     pascal ICError ICFindConfigFile(ICInstance inst, short count, ICDirSpecArrayPtr folders);
  37.     /* count is the number of ICDirSpecs that are valid in folders */
  38.     /* searches the specified folders first, then backs out to preferences folder */
  39.     /* don't you worry about how it finds the file (; */
  40.     /* you can pass nil to folders if count is 0 */
  41.  
  42.     pascal ICError ICSpecifyConfigFile(ICInstance inst, FSSpec *config);
  43.     /* for use *only* by Internet Configuration application */
  44.  
  45.     pascal ICError ICGetSeed(ICInstance inst, long *seed);
  46.     /* returns current seed for prefs file */
  47.     /* this seed changes every time a preference is modified */
  48.     /* poll this to detect preference changes by other applications */
  49.  
  50.     pascal ICError ICGetPerm(ICInstance inst, ICPerm *perm);
  51.     /* returns the permissions currently associated with this file */
  52.     /* mainly used by overriding components, applications normally */
  53.     /* know what permissions they have */
  54.  
  55.     pascal ICError ICBegin(ICInstance inst, ICPerm perm);
  56.     /* start reading/writing the preferences */
  57.     /* must be balanaced by a ICEnd */
  58.     /* do not call WaitNextEvent between this pair */
  59.     /* specify either icReadOnlyPerm or icReadWritePerm */
  60.     /* note that this may open resource files and leave them open until ICEnd */
  61.  
  62.     pascal ICError ICGetPref(ICInstance inst, ConstStr255Param key, ICAttr *attr, Ptr buf, long *size);
  63.     /* this routine may be called without a ICBegin/ICEnd pair, in which case */
  64.     /* it implicitly calls ICBegin(inst, icReadOnlyPerm */
  65.     /* given a key string, returns the attributes and the (optionally) the data for a preference */
  66.     /* key must not be the empty string */
  67.     /* if buf is nil then no data fetched and incoming size is ignored*/
  68.     /* size must be non-negative, is size of allocated space for data at buf */
  69.     /* attr and size and always set on return */
  70.     /* size is actual size of data (if key present); */
  71.     /* attr is pref attributes */
  72.      /* if icTruncatedErr then everything is valid, except you lost some data, size is size of real data*/
  73.     /* on other errors, attr is ICattr_no_change and size is 0 */
  74.  
  75.     pascal ICError ICSetPref(ICInstance inst, ConstStr255Param key, ICAttr attr, Ptr buf, long size);
  76.     /* this routine may be called without a ICBegin/ICEnd pair, in which case */
  77.     /* it implicitly calls ICBegin(inst, icReadWritePerm */
  78.     /* given a key string, sets the attributes and the data for a preference (either is optional); */
  79.     /* key must not be the empty string */
  80.     /* if buf is nil then no data stored and size is ignored, used for setting attr */
  81.     /* size must be non-negative, is size of the data at buf to store */
  82.     /* icPermErr if ICBegin was given icReadOnlyPerm */
  83.     /* icPermErr if current attr is locked, new attr is locked and buf <> nil */
  84.  
  85.     pascal ICError ICCountPref(ICInstance inst, long *count);
  86.     /* count total number of preferences */
  87.     /* if error then count is 0 */
  88.  
  89.     pascal ICError ICGetIndPref(ICInstance inst, long n, Str255 key);
  90.     /* return the key of the Nth preference */
  91.     /* n must be positive */
  92.     /* icPrefNotFoundErr if n is beyond the last preference */
  93.  
  94.     pascal ICError ICDeletePref(ICInstance inst, ConstStr255Param key);
  95.     /* delete the preference specified by key */
  96.     /* key must not be the empty string */
  97.     /* preference specified by key must be present */
  98.     /* icPrefNotFoundErr if it isn't */
  99.  
  100.     pascal ICError ICEnd(ICInstance inst);
  101.     /* stop reading/writing the preferences */
  102.  
  103.     pascal ICError ICDefaultFileName(ICInstance inst, Str63 name);
  104.     /* return the default file name */
  105.     /* the component calls this routine to set up the default internet configuration file name*/
  106.     /* this allows this operation to be intercepted by a component that has captured us */
  107.     /* it currently gets it from the component resource file */
  108.     /* the glue version is hardwired */
  109.  
  110.     pascal ICError ICGetComponentInstance(ICInstance inst, Ptr *component_inst);
  111.     /* returns noErr and the component instance that we're talking to, if we're using the component */
  112.     /* returns an error and nil if we're doing it with glue */
  113.  
  114. #ifdef __cplusplus
  115. }
  116. #endif __cplusplus
  117.  
  118. #endif
  119.